ShareWare OnLine 2

home *** CD-ROM | disk | FTP | other *** search

/ ShareWare OnLine 2 / ShareWare OnLine Volume 2 (CMS Software)(1993).iso / os2 / remin301.zip / REMIND.MAN < prev next >

Wrap

Text File | 1993-01-16 | 102KB | 2,509 lines

REMIND(1) REMIND(1) NNAAMMEE remind - a sophisticated reminder service SSYYNNOOPPSSIISS rreemmiinndd [[_o_p_t_i_o_n_s] _f_i_l_e_n_a_m_e [_d_a_t_e] DDEESSCCRRIIPPTTIIOONN RReemmiinndd reads the supplied _f_i_l_e_n_a_m_e and executes the com- mands found in it. The commands are used to issue reminders and alarms. Each reminder or alarm can consist of a message sent to standard output, or a program to be executed. OOPPTTIIOONNSS --nn The --nn option causes RReemmiinndd to print the nneexxtt occurrence of each reminder in a simple calendar format. You can sort this by date by piping the output through ssoorrtt((11)). --rr The --rr option disables RRUUNN directives and the sshheellll(()) function --cc_n The --cc option causes RReemmiinndd to produce a calendar which is sent to standard output. If you supply a number _n, then a calendar will be generated for _n months, starting with the current month. By default, a calendar for only the current month is produced. If _n starts with '+', then a calendar for _n weeks is produced. --ww_n The --ww option specifies the output width of the formatted calendar, in columns. By default, the calendar is formatted for an 80-column device. --ss_n The --ss option is very similar to the --cc option, except that the output calendar is not formatted. It is listed in a "simple format" which can be used as input for more sophisticated calendar-drawing programs. --pp_n The --pp option is very similar to the --ss option, except that the output contains additional informa- tion for use by the rreemm22ppss program, which creates a PostScript calendar. --vv The --vv option makes the output of RReemmiinndd slightly more verbose. --oo The --oo option causes RReemmiinndd to ignore all OONNCCEE directives. --tt The --tt option causes RReemmiinndd to trigger all non- expired reminders, regardless of the _d_e_l_t_a supplied for each reminder. 11 November 1992 1 REMIND(1) REMIND(1) --hh The --hh option ("hush...") supresses certain warning and information messages. In particular, if no reminders are triggered, this mode produces no out- put. --aa The --aa option causes RReemmiinndd not to immediately trigger timed reminders which would also be queued. --qq The --qq option causes RReemmiinndd not to queue timed reminders for later execution. --ff The --ff option causes RReemmiinndd to remain in the fore- ground when processing queued reminders, rather than forking off a background process to handle them. --ee The --ee option diverts error messages (normally sent to the standard error stream) to the standard out- put stream. --dd_c_h_a_r_s The --dd option enables certain debugging modes. The _c_h_a_r_s specify which modes to enable: ee Echo all input lines xx Trace all expression evaluation tt Display all trigger date computation vv Dump the variable table after execution of the reminder script ll Echo lines when displaying error messages --bb[_n] Set the time format for the calendar and simple- calendar outputs. _N can range from 0 to 2, with the default 0. A value of 0 causes times to be inserted in 12-hour (am/pm) format. 1 causes times to be inserted in 24-hour format, and 2 inhibits the automatic insertion of times in the calendar output. --xx[_n] Sets the iteration limit for the SSAATTIISSFFYY clause of a RREEMM command. Defaults to 150. --zz[_n] Runs RReemmiinndd in the daemon mode. If _n is supplied, it specifies how often (in minutes) RReemmiinndd should wake up to check if the reminder script has been changed. _N defaults to 5, and can range from 5 to 60. Note that the use of the --zz option also enables the --ff option. If you supply a _d_a_t_e on the command line, it must consist 11 November 1992 2 REMIND(1) REMIND(1) of _d_a_y _m_o_n_t_h _y_e_a_r, where _d_a_y is the day of the month, _m_o_n_t_h is at least the first three letters of the English name of the month, and _y_e_a_r is a year (all 4 digits) from 1990 to about 2075. You can leave out the _d_a_y, which then defaults to 1. If you do supply a _d_a_t_e on the command line, then RReemmiinndd uses it, rather than the actual system date, as its notion of "today." This lets you create calendars for future months, or test to see how your reminders will be trig- gered in the future. RREEMMIINNDDEERR FFIILLEESS RReemmiinndd uses scripts to control its operation. The com- mands inside a script can range from the very simple and almost immediately understandable: REM 6 Jan MSG David's birthday to the baroque and obscure: REM [trigger(date(thisyear, 1, 1) + 180)] ++5 OMIT \ sat sun SKIP MSG [ord(thisyear-1980)] payment due %b! A reminder file consists of commands, with one command per line. Several lines can be continued using the backslash character, as in the above example. In this case, all of the concatenated lines are treated as a single line by RReemmiinndd. Note that if an error occurs, RReemmiinndd reports the line number of the last line of a continued line. RReemmiinndd ignores blank lines, and lines beginning with the '#' or ';' characters. You can use the semicolon as a comment character if you wish to pass a RReemmiinndd script through the C pre-processor, which interprets the '#' character as the start of a pre-processing directive. RReemmiinndd is not case sensitive; you can generally use any mixture of upper- or lower-case for commands, parameters, invocation options, etc. TTHHEE RREEMM CCOOMMMMAANNDD The most powerful command in a RReemmiinndd script is the RREEMM command. This command is responsible for issuing reminders. Its syntax is: RREEMM [OONNCCEE] [_d_a_t_e___s_p_e_c] [_b_a_c_k] [_d_e_l_t_a] [_r_e_p_e_a_t] [SSKKIIPP | BBEEFFOORREE | AAFFTTEERR] [OOMMIITT _o_m_i_t___l_i_s_t] [AATT _t_i_m_e [_t_d_e_l_t_a] [_t_r_e_p_e_a_t]] [UUNNTTIILL _e_x_p_i_r_y___d_a_t_e] MMSSGG | RRUUNN | CCAALL | SSAATTIISSFFYY _b_o_d_y The parts of the RREEMM command can be specified in any order, except that the _b_o_d_y must come immediately after the MMSSGG, RRUUNN, CCAALL or SSAATTIISSFFYY keyword. 11 November 1992 3 REMIND(1) REMIND(1) The RREEMM token is optional, providing that the remainder of the command cannot be mistaken for another RReemmiinndd command such as OOMMIITT or RRUUNN. The portion of the RREEMM command before the MMSSGG, RRUUNN, CCAALL or SSAATTIISSFFYY clause is called a _t_r_i_g_g_e_r. MMSSGG,, RRUUNN,, aanndd CCAALL The keywords MMSSGG, RRUUNN and CCAALL denote the _t_y_p_e of the reminder. (SSAATTIISSFFYY is more complicated and will be explained later.) A MMSSGG type reminder simply prints a message to the standard output, after passing the _b_o_d_y through a special substitution filter, described in the section "The Substitution Filter." A RRUUNN-type reminder also passes the _b_o_d_y through the substitution filter, but then executes the result as a system command. A CCAALL-type reminder is used only to place entries in the calendar produced when RReemmiinndd is run with the -c or -s options. DDAATTEE SSPPEECCIIFFIICCAATTIIOONNSS A _d_a_t_e___s_p_e_c consists of zero to four parts. These parts are _d_a_y (day of month), _m_o_n_t_h (month name), _y_e_a_r and _w_e_e_k_- _d_a_y_. _M_o_n_t_h and _w_e_e_k_d_a_y are the English names of months and weekdays. At least the first three characters must be used. The following are examples of the various parts of a _d_a_t_e___s_p_e_c_: _d_a_y_: 1, 22, 31, 14, 3 _m_o_n_t_h_: JANUARY, feb, March, ApR, may, Aug _y_e_a_r_: 1990, 1993, 2030, 95 (interpreted as 1995). The year can range from 1990 to 2075. _w_e_e_k_d_a_y_: Monday, tue, Wed, THU, Friday, saturday, sundAy Note that there can be several _w_e_e_k_d_a_y components sepa- rated by spaces in a _d_a_t_e___s_p_e_c_. IINNTTEERRPPRREETTAATTIIOONN OOFF DDAATTEE SSPPEECCIIFFIICCAATTIIOONNSS The following examples show how date specifications are interpreted. 1. Null date specification - the reminder is triggered every day. The trigger date for a specific run is simply the current system date. 2. Only _d_a_y present. The reminder is triggered on the specified day of each month. The trigger date for a par- ticular run is the closest such day to the current system date. For example: 11 November 1992 4 REMIND(1) REMIND(1) REM 1 MSG First of every month. REM 31 MSG 31st of every month that has 31 days. 3. Only _m_o_n_t_h present. The reminder is triggered every day of the specified month. Example: REM Feb MSG Every day in February 4. _d_a_y and _m_o_n_t_h present. Examples: REM 6 Jan MSG Every 6th of January REM Feb 29 MSG Every 29th of February 5. Only _y_e_a_r present. Example: REM 1991 MSG Every day in 1991 6. _y_e_a_r and _d_a_y present. Examples: REM 1 1990 MSG 1st of every month in 1990 REM 1992 23 MSG 23rd of every month in 1992 7. _y_e_a_r and _m_o_n_t_h present. Examples: REM Feb 1991 MSG Every day in Feb 1991 REM 1992 September MSG Every day in Sept 1992 8. _y_e_a_r_, _m_o_n_t_h and _d_a_y present. Examples: REM 8 Jan 1991 MSG 8th January 1991. REM 1992 March 9 MSG 9th March 1992. 9. _w_e_e_k_d_a_y only. Examples: REM Sat MSG Every Saturday REM Mon Tue Wed Thu Fri MSG Every working day REM Monday Wednesday MSG Every Monday and Wednesday 10. _w_e_e_k_d_a_y and _d_a_y present. Examples: REM Sat 1 MSG First Saturday of every month REM Mon Tue Wed Thu Fri 15 \ MSG 1st working day after 15th of every month 11. _w_e_e_k_d_a_y and _m_o_n_t_h present. Examples: REM Mon March MSG Every Monday in March REM Mon Tue Wed Thu Fri Feb MSG Every working day in February 12. _w_e_e_k_d_a_y_, _m_o_n_t_h and _d_a_y present. Examples: REM Mon 1 March MSG First Monday in March REM Sat Sun 15 July MSG First Sat or Sun on or after 15 July 13. _w_e_e_k_d_a_y and _y_e_a_r present. Example: REM Sat Sun 1991 MSG Every Saturday and Sunday in 1991 14. _w_e_e_k_d_a_y_, _d_a_y and _y_e_a_r present. Examples: REM Mon 15 1990 MSG 1st Mon after 15th of every month in 1990 REM Mon Tue Wed Thu Fri 1 1990 \ MSG 1st working day of every month in 1990 15. _w_e_e_k_d_a_y_, _m_o_n_t_h and _y_e_a_r present. Example: REM Mon Wed 1991 Feb MSG Every Mon and Wed in Feb 1991. 11 November 1992 5 REMIND(1) REMIND(1) 16. _w_e_e_k_d_a_y_, _d_a_y_, _m_o_n_t_h and _y_e_a_r present. Example: REM Mon Tue Wed Thu Fri 28 Oct 1990 \ MSG 1st working day on or after 28 October 1990. Note that when both _w_e_e_k_d_a_y and _d_a_y are specified, RReemmiinndd chooses the first date on or after the specified _d_a_y which also satisfies the _w_e_e_k_d_a_y constraint. It does this by picking the first date on or after the specified _d_a_y which is listed in the list of _w_e_e_k_d_a_y_s_. Thus, a reminder like: REM Mon Tue 28 Oct 1990 MSG Hi would be issued only on Monday, 29 October, 1990. It would not be issued on Tuesday, 30 October, 1990, since the 29th is the first date to satisfy the _w_e_e_k_d_a_y con- straints. BBAACCKKWWAARRDD SSCCAANNNNIINNGG Sometimes, it is necessary to specify a date as being a set amount of time before another date. For example, the last Monday in a given month is computed as the first Mon- day in the next month, minus 7 days. The _b_a_c_k specifica- tion in the reminder is used in this case: REM Mon 1 -7 MSG Last Monday of every month. A _b_a_c_k is specified with one or two dashes followed by an integer. This causes RReemmiinndd to move "backwards" from what would normally be the trigger date. The difference between --7 and -7 will be explained when the OOMMIITT keyword is described. AADDVVAANNCCEE WWAARRNNIINNGG For some reminders, it is appropriate to receive advance warning of the event. For example, you may wish to be reminded of someone's birthday several days in advance. The _d_e_l_t_a portion of the RREEMM command achieves this. It is specified as one or two "+" signs followed by a number _n. Again, the difference between the "+" and "++" forms will be explained under the OOMMIITT keyword. RReemmiinndd will trigger the reminder on computed trigger date, as well as on each of the _n days before the event. Here are some examples: REM 6 Jan +5 MSG Remind me of birthday 5 days in advance. The above example would be triggered every 6th of January, as well as the 1st through 5th of January. PPEERRIIOODDIICC RREEMMIINNDDEERRSS We have already seen some built-in mechanisms for certain types of periodic reminders. For example, an event 11 November 1992 6 REMIND(1) REMIND(1) occurring every Wednesday could be specified as: REM Wed MSG Event! However, events which do not repeat daily, weekly, monthly or yearly require another approach. The _r_e_p_e_a_t component of the RREEMM command fills this need. To use it, you must completely specify a date (year, month and day, and optionally weekday.) The _r_e_p_e_a_t component is an asterisk followed by a number specifying the repetition period in days. For example, suppose you get paid every second Wednesday, and your last payday was Wednesday, 28 October, 1992. You can use: REM 28 Oct 1992 *14 MSG Payday This issues the reminder every 14 days, starting from the calculated trigger date. You can use _d_e_l_t_a and _b_a_c_k with _r_e_p_e_a_t_. Note, however, that the _b_a_c_k is used only to com- pute the initial trigger date; thereafter, the reminder repeats with the specified period. Similarly, if you specify a weekday, it is used only to calculate the ini- tial date, and does not affect the repetition period. EEXXPPIIRRYY DDAATTEESS Some reminders should be issued periodically for a certain time, but then expire. For example, suppose you have a class every Friday, and that your last class is on 11 December 1992. You can use: REM Fri UNTIL 11 Dec 1992 MSG Class today. Another example: Suppose you have jury duty from 30 November 1992 until 4 December 1992. The following reminder will issue the message every day of your jury duty, as well as 2 days ahead of time: REM 30 Nov 1992 *1 +2 UNTIL 4 Dec 1992 MSG Jury duty Note that the _r_e_p_e_a_t of *1 is necessary; without it, the reminder would be issued only on 30 November (and the two days preceding.) TTHHEE OONNCCEE KKEEYYWWOORRDD Sometimes, it is necessary to ensure that reminders are run only once on a given day. For example, if you have a reminder which makes a backup of your files every Friday: REM Fri RUN do_backup 11 November 1992 7 REMIND(1) REMIND(1) (Here, _d_o___b_a_c_k_u_p is assumed to be a program or shell script which does the work.) If you run RReemmiinndd from your .login script, for example, and log in several times per day, the _d_o___b_a_c_k_u_p program will be run each time you log in. If, however, you use the OONNCCEE keyword in the reminder, the RReemmiinndd checks the last access date of the reminder script. If it is the same as the current date, RReemmiinndd assumes that it has already been run, and will not issue reminders containing the OONNCCEE keyword. Note that if you view or edit your reminder script, the last access date will be updated, and the OONNCCEE keyword will not operate properly. If you start RReemmiinndd with the --oo option, then the OONNCCEE keyword will be ignored. LLOOCCAALLLLYY OOMMIITTTTIINNGG WWEEEEKKDDAAYYSS The OOMMIITT portion of the RREEMM command is used to "omit" cer- tain days when counting the _d_e_l_t_a or _b_a_c_k. It is speci- fied using the keyword OOMMIITT followed by a list of week- days. Its action is best illustrated with examples: REM 1 +1 OMIT Sat Sun MSG Important Event This reminder is normally triggered on the first of every month, as well as the day preceding it. However, if the first of the month falls on a Sunday or Monday, then the reminder is triggered starting from the previous Friday. This is because the _d_e_l_t_a of +1 does not count Saturday or Sunday when it counts backwards from the trigger date to determine how much advance warning to give. Contrast this with the use of "++1" in the above command. In this case, the reminder is triggered on the first of each month, as well as the day preceding it. The omitted days are counted. REM 1 -1 OMIT Sat Sun MSG Last working day of month Again, in the above example, the _b_a_c_k of -1 normally causes the trigger date to be the last day of the month. However, because of the OOMMIITT clause, if the first of the month falls on a Sunday or Monday, the trigger date is moved backwards past the weekend to Friday. (If you have globally omitted holidays, the reminder will be moved back past them, also. See "The OMIT command" for more details.) By comparison, if we had used "--1", the reminder would be triggered on the last day of the month, regardless of the OOMMIITT. TTIIMMEEDD RREEMMIINNDDEERRSS 11 November 1992 8 REMIND(1) REMIND(1) Timed reminders are those which have an AATT keyword fol- lowed by a _t_i_m_e and optional _t_d_e_l_t_a and _t_r_e_p_e_a_t. The _t_i_m_e must be specified in 24-hour format, with 0:00 represent- ing midnight, 12:00 representing noon, and 23:59 repre- senting one minute to midnight. RReemmiinndd treats timed reminders specially. If the trigger date for a timed reminder is the same as the current sys- tem date, the reminder is queued for later activation. When RReemmiinndd has finished processing the reminder file, it puts itself in the background, and activates timed reminders when the system time reached the specified time. If the trigger date is _n_o_t the same as the system date, the reminder is not queued. For example, the following reminder, triggered every work- ing day, will emit a message telling you to leave at 5:00pm: REM Mon Tue Wed Thu Fri AT 17:00 MSG Time to leave! The following reminder will be triggered on Thursdays and Fridays, but will only be queued on Fridays: REM Fri ++1 AT 13:00 MSG Lunch at 1pm Friday. The _t_d_e_l_t_a and _t_r_e_p_e_a_t have the same form as a _r_e_p_e_a_t and _d_e_l_t_a, but are specified in minutes. For example, this reminder will be triggered at 12:00pm as well as 45 min- utes before: REM AT 12:00 +45 MSG Example The following will be issued starting at 10:45, every half hour until 11:45, and again at noon. REM AT 12:00 +75 *30 MSG Example2 The "+75" means that the reminder is issued starting 75 minutes before noon; in other words, at 10:45. The *30 specifies that the reminder is subsequently to be issued every 30 minutes. Note that the reminder is always issued at the specified time, even if the _t_d_e_l_t_a is not a multi- ple of the _t_r_e_p_e_a_t. So the above example is issued at 10:45am, 11:15am, 11:45am, and 12:00pm. Note that in the time specification, there is no distinction between the "+" and "++" forms of _t_d_e_l_t_a. Normally, RReemmiinndd will issue timed reminders as it pro- cesses the reminder script, as well as queuing them for later. If you do not want RReemmiinndd to issue the reminders when processing the script, but only to queue them for later, use the --aa command-line option. If you do not want 11 November 1992 9 REMIND(1) REMIND(1) reminders to be queued for later, use the --qq command-line option. Normally, RReemmiinndd forks a background process to handle queued reminders. If you want RReemmiinndd to remain in the foreground, use the --ff command-line option. This is use- ful, for example, in .xinitrc scripts, where you can use the command: remind -fa myreminders & This ensures that when you exit X-Windows, the RReemmiinndd pro- cess is killed. WWAARRNNIINNGG AABBOOUUTT TTIIMMEEDD RREEMMIINNDDEERRSS Note: If you use user-defined functions or variables (described later) in the bodies of timed reminders, then when the timed reminders are activated, the variables and functions have the definitions which were in effect at the end of the reminder script. These definitions may _n_o_t necessarily be those which were in effect at the time the reminder was queued. TTHHEE SSUUBBSSTTIITTUUTTIIOONN FFIILLTTEERR Before being processed, the body of a RREEMM command is passed through a substitution filter. The filter scans for sequences "%x" (where "x" is any letter and certain other characters) and performs substitutions as shown below. (All dates refer to the trigger date of the reminder.) %%aa is replaced with "on _w_e_e_k_d_a_y_, _d_a_y _m_o_n_t_h_, _y_e_a_r" For example, consider the reminder: REM 18 Oct 1990 +4 MSG Meeting with Bob %a. On 16 October 1990, it would print "Meeting with Bob on Thursday, 18 October, 1990." On 17 October 1990, it would print "Meeting with Bob tomorrow." On 18 October 1990, it would print "Meeting with Bob today." %%bb is replaced with "in _d_i_f_f day's time" where _d_i_f_f is the aaccttuuaall number of days between the current date and the trigger date. (OOMMIITTss have no effect.) For example, consider: REM 18 Oct 1990 +4 MSG Meeting with Bob %b. 11 November 1992 10 REMIND(1) REMIND(1) On 16 October 1990, it would print "Meeting with Bob in 2 days' time." On 17 October 1990, it would print "Meeting with Bob tomorrow." On 18 October 1990, it would print "Meeting with Bob today." %%cc is replaced with "on _w_e_e_k_d_a_y" Example: REM 18 Oct 1990 +4 MSG Meeting with Bob %c. On 16 October 1990, it would print "Meeting with Bob on Thursday." On 17 October 1990, it would print "Meeting with Bob tomorrow." On 18 October 1990, it would print "Meeting with Bob today." %%dd is replaced with "_d_a_y", the day of the month. %%ee is replaced with "on _d_d_/_m_m_/_y_y_y_y" %%ff is replaced with "on _m_m_/_d_d_/_y_y_y_y" %%gg is replaced with "on _w_e_e_k_d_a_y_, _d_a_y _m_o_n_t_h" %%hh is replaced with "on _d_d_/_m_m" %%ii is replaced with "on _m_m_/_d_d" %%jj is replaced with "on _w_e_e_k_d_a_y_, _m_o_n_t_h _d_a_y_-_t_h_, _y_e_a_r" This form appends the characters "st", "nd", "rd" or "th" to the day of the month, as appropriate. %%kk is replaced with "on _w_e_e_k_d_a_y_, _m_o_n_t_h _d_a_y_-_t_h" %%ll is replaced with "on _y_y_y_y_/_m_m_/_d_d" %%mm is replaced with "_m_o_n_t_h", the name of the month. %%nn is replaced with the number (1 to 12) of the month. %%oo is replaced with " (today)" if and only if the cur- rent system date is the same as the date being used by RReemmiinndd as the current date. Recall that you can specify a date for RReemmiinndd to use on the command line. This substitution is not generally useful in a RREEMM command, but is useful in a BBAANNNNEERR command. (See "The BANNER Command.") 11 November 1992 11 REMIND(1) REMIND(1) %%pp is replaced with "s" if the _d_i_f_f between the cur- rent date and the trigger date is not 1. You can use this to construct reminders like: REM 1 Jan +4 MSG %x day%p to go before New Year! %%qq is replaced with "'s" if the _d_i_f_f between the trig- ger date and the current date is 1. Otherwise, it is replaced with "s'" This can be used as follows: REM 1 Jan +4 MSG New Year in %x day%q time! %%rr is replaced with the day of the month (01 to 31) padded with a leading zero if needed to pad to two digits. %%ss is replaced with "st", "nd", "rd" or "th" depending on the day of the month. %%tt is replaced with the number of the month (01 to 12) padded to two digits with a leading zero. %%uu is replaced with "on _w_e_e_k_d_a_y_, _d_a_y_-_t_h _m_o_n_t_h_, _y_e_a_r" This is similar to %%aa except that "st", "nd", "rd" or "th" is added to the _d_a_y as appropriate. %%vv is replaced with "on _w_e_e_k_d_a_y_, _d_a_y_-_t_h _m_o_n_t_h" %%ww is replaced with "_w_e_e_k_d_a_y", the name of the day of the week. %%xx is replaced with the _d_i_f_f between the current date and the trigger date. The _d_i_f_f is defined as the actual number of days between these two dates; OOMMIITTss are not counted. (Strict date subtraction is performed.) %%yy is replaced with "_y_e_a_r", the year of the trigger date. %%zz is replaced with "_y_y", the last two digits of the year. %%__ (percent-underscore) is replaced with a newline. You can use this to achieve multi-line reminders. %%11 is replaced with "now", "_m minutes from now", "_m minutes ago", "_h hours from now", "_h hours ago", "_h hours and _m minutes from now" or "_h hours and _m minutes ago", as appropriate for a timed reminder. Note that unless you specify the --aa option, timed reminders will be triggered like normal reminders, and thus a timed reminder which occurred earlier in the day may be triggered. This causes the need for the "...ago" forms. 11 November 1992 12 REMIND(1) REMIND(1) %%22 is replaced with "at _h_h:_m_mam" or "..pm" depending on the AATT time of the reminder. %%33 is replaced with "at _h_h:_m_m" in 24-hour format. %%44 is replaced with "_m_m" where _m_m is the number of minutes between "now" and the time specified by AATT. If the AATT time is earlier than the current time, then the result is negative. %%55 is replaced with "_m_a" where _m_a is the absolute value of the number produced by %%44. %%66 is replaced with "ago" or "from now", depending on the relationship between the AATT time and the cur- rent time. %%77 is replaced with the number of hours between the AATT time and the current time. It is always non- negative. %%88 is replaced with the number of minutes between the AATT time and the current time, after the hours (%%77) have been subtracted out. This is a number ranging from 0 to 59. %%99 is replaced with "s" if the value produced by %%88 is not 1. %%00 is replaced with "s" if the value produced by %%77 is not 1. %%!! is replaced with "is" if the current time is before the AATT time, or "was" if it is after. %%@@ is similar to %%22 but displays the current time. %%## is similar to %%33 but displays the current time. %%"" (percent-doublequote) is removed. This sequence is not used by the substitution filter, but is used to tell rreemmiinndd which text to include in a calendar entry when the --cc option is chosen. See "Calendar Mode" Notes: o RReemmiinndd normally prints a blank line after each reminder; if the last character of the body is "%", the blank line will not be printed. o Substitutions a, b, c, e, f, g, h, i, j, k, l, u and v all are replaced with "today" if the current date equals the trigger date, or "tomorrow" if the 11 November 1992 13 REMIND(1) REMIND(1) trigger date is one day after the current date. Thus, they are nnoott the same as substitutions built up from the simpler %w, %y, etc. sequences. o Any of the substitutions dealing with time (0 through 9 and '!') produce undefined results if used in a reminder which does not have an AATT key- word. Also, if a reminder has a _d_e_l_t_a and may be triggered on several days, the time substitutions ignore the date. Thus, the %%11 substitution may report that a meeting is in 15 minutes, for exam- ple, even though it may only be in 2 days time, because a _d_e_l_t_a has triggered the reminder. It is recommended that you use the time substitutions only in timed reminders with no _d_e_l_t_a which are designed to be queued for timed activation. o Capital letters can be used in the substitution sequence, in which case the first character of the substituted string is capitalized (if it is nor- mally a lower-case letter.) o All other characters following a "%" sign are sim- ply copied. In particular, to get a "%" sign out, use "%%" in the body. To start the body of a reminder with a space, use "% ", since rreemmiinndd nor- mally scans for the first non-space character after a MMSSGG,, CCAALL or RRUUNN token. TTHHEE OOMMIITT CCOOMMMMAANNDD In addition to being a keyword in the RREEMM command, OOMMIITT is a command in its own right. Its syntax is: OOMMIITT _d_a_y _m_o_n_t_h [_y_e_a_r] The OOMMIITT command is used to "globally" omit certain days, which are usually holidays. These globally-omitted days are skipped by the "-" and "+" forms of _b_a_c_k and _d_e_l_t_a. Some examples: OMIT 1 Jan OMIT 7 Sep 1992 The first example specifies a holiday which occurs on the same date each year - New Year's Day. The second example specifies a holiday which changes each year - Labour Day. For these types of holidays, you must create an OOMMIITT com- mand for each year. (Later, in the description of expres- sions and some of the more advanced features of RReemmiinndd, you will see how to automate this for some cases.) For convenience, you can use a _d_e_l_t_a and MMSSGG or RRUUNN key- word in the OOMMIITT command. The following sequences are exactly equivalent: 11 November 1992 14 REMIND(1) REMIND(1) OMIT 1 Jan REM 1 Jan +4 MSG New year's day is %b! and OMIT 1 Jan +4 MSG New year's day is %b! TTHHEE BBEEFFOORREE,, AAFFTTEERR AANNDD SSKKIIPP KKEEYYWWOORRDDSS Normally, days which are omitted, whether by a global OOMMIITT command or the local OOMMIITT keyword in a RREEMM statement, only affect the counting of the -_b_a_c_k or the +_d_e_l_t_a. For exam- ple, suppose you have a meeting every Wednesday. Suppose, too, that you have indicated 11 Nov as a holiday: OMIT 11 Nov +4 MSG Remembrance Day REM Wed +1 MSG Code meeting %b. The above sequence will issue a reminder about a meeting for 11 November 1992, which is a Wednesday. This is prob- ably incorrect. There are three options: BBEEFFOORREE This keyword moves the reminder to before any omit- ted days. Thus, in the above example, use of BBEEFFOORREE would cause the meeting reminder to be trig- gered on Tuesday, 10 November 1992. AAFFTTEERR This keyword moves the reminder to after any omit- ted days. In the above example, the meeting reminder would be triggered on Thursday, 12 Novem- ber 1992. SSKKIIPP This keyword causes the reminder to be skipped com- pletely on any omitted days. Thus, in the above example, the reminder would not be triggered on 11 November 1992. However, it would be triggered as usual on the following Wednesday, 18 November 1992. The BBEEFFOORREE and AAFFTTEERR keywords move the trigger date of a reminder to before or after a block of omitted days, respectively. Suppose you normally run a backup on the first day of the month. However, if the first day of the month is a weekend or holiday, you run the backup on the first working day following the weekend or holiday. You could use: REM 1 OMIT Sat Sun AFTER RUN do_backup Let's examine how the trigger date is computed. The 11 specifies the first day of the month. The local OOMMIITT key- word causes the AAFFTTEERR keyword to move the reminder forward past weekends. Finally, the AAFFTTEERR keyword will keep mov- ing the reminder forward until it has passed any holidays specified with global OOMMIITT commands. 11 November 1992 15 REMIND(1) REMIND(1) TTHHEE IINNCCLLUUDDEE CCOOMMMMAANNDD RReemmiinndd allows you to include other files in your reminder script, similar to the C preprocessor #include directive. For example, your system administrator may maintain a file of holidays or system-wide reminders. You can include these in your reminder script as follows: INCLUDE /usr/share/remind/holidays INCLUDE /usr/share/remind/reminders (The actual pathnames vary from system to system - ask your system administrator.) IINNCCLLUUDDEE files can be nested up to a depth of 8. TTHHEE RRUUNN CCOOMMMMAANNDD If you include other files in your reminder script, you may not always entirely "trust" the contents of the other files. For example, they may contain RRUUNN-type reminders which could be used to access your files or perform unde- sired actions. The RRUUNN command can restrict this: If you include the command RRUUNN OOFFFF in your top-level reminder script, any reminder or expression which would normally execute a system command is disabled. RRUUNN OONN will re- enable the execution of system commands. Note that the RRUUNN command can _o_n_l_y be used in your top-level reminder script; it will _n_o_t work in any files accessed by the IINNCCLLUUDDEE command. This is to protect you from someone placing a RRUUNN OONN command in an included file. If you run RReemmiinndd with the --rr command-line option, RRUUNN- type reminders and the sshheellll(()) function will be disabled, regardless of any RRUUNN commands in the reminder script. One use of the RRUUNN command is to provide a secure inter- face between RReemmiinndd and the EEllmm mail system. The EEllmm sys- tem can automatically scan incoming mail for reminder or calendar entries, and place them in your calendar file. To use this feature, you should set the calendar filename option under EEllmm to be something like "~/.reminders.in", _n_o_t your main reminder file! This is so that any RRUUNN OONN commands mailed to you can never be activated. Then, you can use the EEllmm _s_c_a_n _m_e_s_s_a_g_e _f_o_r _c_a_l_e_n_d_a_r _e_n_t_r_i_e_s command to place reminders prefaced by "->" into .reminders.in. In your main .reminders file, include the following lines: RUN OFF # Disable RUN INCLUDE .reminders.in RUN ON # Re-enable RUN 11 November 1992 16 REMIND(1) REMIND(1) TTHHEE BBAANNNNEERR CCOOMMMMAANNDD When RReemmiinndd first issues a reminder, it prints a message like this: Reminders for Friday, 30th October, 1992 (today): The BBAANNNNEERR command lets you change the format. It should appear before any RREEMM commands. The format is: BBAANNNNEERR _f_o_r_m_a_t The _f_o_r_m_a_t is similar to the _b_o_d_y of a RREEMM command. It is passed through the substitution filter, with an implicit trigger of the current system date. Thus, the default banner is equivalent to: BANNER Reminders for %w, %d%s %m, %y%o: You can disable the banner completely with BANNER %. Or you can create a custom banner: BANNER Hi - here are your reminders for %y/%t/%r: CCOONNTTRROOLLLLIINNGG TTHHEE OOMMIITT CCOONNTTEEXXTT Sometimes, it is necessary to temporarily change the global OOMMIITTss which are in force for a few reminders. Three commands allow you to do this: PPUUSSHH--OOMMIITT--CCOONNTTEEXXTT This command saves the current global OOMMIITTss on an internal stack. CCLLEEAARR--OOMMIITT--CCOONNTTEEXXTT This command clears all of the global OOMMIITTss, start- ing you off with a "clean slate." PPOOPP--OOMMIITT--CCOONNTTEEXXTT This command restores the global OOMMIITTss which were saved by the most recent PPUUSSHH--OOMMIITT--CCOONNTTEEXXTT. For example, suppose you have a block of reminders which require a clear OOMMIITT context, and that they also introduce unwanted global OOMMIITTss which could interfere with later reminders. You could use the following fragment: PUSH-OMIT-CONTEXT # Save the current context CLEAR-OMIT-CONTEXT # Clean the slate # Block of reminders goes here POP-OMIT-CONTEXT # Restore the saved omit context EEXXPPRREESSSSIIOONNSS In certain contexts, to be described later, RReemmiinndd will accept expressions for evaluation. RReemmiinndd expressions resemble C expressions, but operate on different types of 11 November 1992 17 REMIND(1) REMIND(1) objects. DDAATTAA TTYYPPEESS RReemmiinndd expressions understand four types of objects: IINNTT The IINNTT data type consists of the integers repre- sentable in one machine word. The IINNTT data type corresponds to the C "int" type. SSTTRRIINNGG The SSTTRRIINNGG data type consists of strings of charac- ters. It is somewhat comparable to a C character array, but more closely resembles the string type in BASIC. TTIIMMEE The TTIIMMEE data type consists of times of the day. The TTIIMMEE data type is internally stored as an inte- ger representing the number of minutes since mid- night. DDAATTEE The DDAATTEE data type consists of dates (later than 1 January 1990.) Internally, DDAATTEE objects are stored as the number of days since 1 January 1990. CCOONNSSTTAANNTTSS The following examples illustrate constants in RReemmiinndd expressions: IINNTT ccoonnssttaannttss 12, 36, -10, 0, 1209 SSTTRRIINNGG ccoonnssttaannttss "Hello there", "This is a test", "\n\gosd\w", "" Note that the empty string is represented by "", and that backslashes in a string are _n_o_t inter- preted specially, as in they are in C. TTIIMMEE ccoonnssttaannttss 12:33, 0:01, 14:15, 16:42 Note that TTIIMMEE constants are written in 24-hour format DDAATTEE ccoonnssttaannttss DDAATTEE constants are expressed as 'yyyy/mm/dd', and the single quotes _m_u_s_t be supplied. This distin- guishes date constants from division of integers. Examples: Note that DDAATTEE constants are _p_r_i_n_t_e_d as _y_y_y_y/_m_m/_d_d without the quotes. Note also that versions of 11 November 1992 18 REMIND(1) REMIND(1) RReemmiinndd prior to 03.00.01 did not support date con- stants. In those versions, you must create dates using the ddaattee(()) function. OOPPEERRAATTOORRSS _R_e_m_i_n_d has the following operators. Operators on the same line have equal precedence, while operators on lower lines have lower precedence than those on higher lines. The operators approximately correspond to C operators. ! - (unary logical negation and arithmetic negation) * / % + - < <= > >= == != && || DDEESSCCRRIIPPTTIIOONN OOFF OOPPEERRAATTOORRSS !! Logical negation. Can be applied to an IINNTT type. If the operand is non-zero, returns zero. Other- wise, returns 1. -- Unary minus. Can be applied to an IINNTT. Returns the negative of the operand. ** Multiplication. Returns the product of two IINNTTs. // Integer division. Returns the quotient of two IINNTTs, discarding the remainder. %% Modulus. Returns the remainder upon dividing one IINNTT by another. ++ Has several uses. These are: IINNTT + IINNTT - returns the sum of two IINNTTs. IINNTT + TTIIMMEE or TTIIMMEE + IINNTT - returns a TTIIMMEE obtained by adding IINNTT minutes to the original TTIIMMEE. IINNTT + DDAATTEE or DDAATTEE + IINNTT - returns a DDAATTEE obtained by adding IINNTT days to the original DDAATTEE. SSTTRRIINNGG + SSTTRRIINNGG - returns a SSTTRRIINNGG which is the concatenation of the two orignal SSTTRRIINNGGs. SSTTRRIINNGG + anything or anything + SSTTRRIINNGG - converts the non-SSTTRRIINNGG argument to a SSTTRRIINNGG, and then per- forms concatenation. See the ccooeerrccee(()) function. 11 November 1992 19 REMIND(1) REMIND(1) -- Has several uses. These are: IINNTT - IINNTT - returns the difference of two IINNTTs. DDAATTEE - DDAATTEE - returns (as an IINNTT) the difference in days between two DDAATTEEs. TTIIMMEE - TTIIMMEE - returns (as an IINNTT) the difference in minutes between two TTIIMMEEs. DDAATTEE - IINNTT - returns a DDAATTEE which is IINNTT days ear- lier than the original DDAATTEE. TTIIMMEE - IINNTT - returns a TTIIMMEE which is IINNTT minutes earlier than the original TTIIMMEE. <<,, <<==,, >>,, aanndd >>== These are the comparison operators. They can take operands of any type, but both operands must be of the same type. The comparison operators return 1 if the comparison is true, or 0 if it is false. Note that string comparison is done following the lexical ordering of characters on your system, and that upper and lower case _a_r_e distinct for these operators. ====,, !!== == tests for equality, returning 1 if its operands are equal, and 0 if they are not. != tests for inequality. If the operands are not of the same type, == returns 0 and != returns 1. Again, string compar- isons are case-sensitive. &&&& This is the logical AND operator. Both of its operands must be of type IINNTT. It returns 1 if both operands are non-zero, and 0 otherwise. |||| This is the logical OR operator. Both of its operands must be of type IINNTT. It returns 1 if either operand is non-zero, and 0 otherwise. NNOOTTEESS Operators of equal precedence are _a_l_w_a_y_s evaluated from left to right, except where parentheses dictate otherwise. This is important, because the enhanced "+" and "-" opera- tors are not necessarily associative. For example: 1 + 2 + "string" + 3 + 4 yields "3string34" 1 + (2 + "string") + (3 + 4) yields "12string7" 12:59 + 1 + "test" yields "13:00test" 12:59 + (1 + "test") yields "12:591test" 11 November 1992 20 REMIND(1) REMIND(1) The logical operators are _n_o_t so-called short-circuit operators, as they are in C. Both operands are always evaluated. Thus, an expression such as: (f!=0) && (100/f <= 3) will cause an error if f is zero. VVAARRIIAABBLLEESS RReemmiinndd allows you to assign values to variables. The SSEETT command is used as follows: SSEETT _v_a_r _e_x_p_r _V_a_r is the name of a variable. It must start with a let- ter or underscore, and consist only of letters, digits and underscores. Only the first 12 characters of a variable name are significant. Variable names are _n_o_t case sensi- tive; thus, "Afoo" and "afOo" are the same variable. Examples: SET a 10 + (9*8) SET b "This is a test" SET mydir getenv("HOME") SET time 12:15 SET date today() Note that variables themselves have no type. They take on the type of whatever you store in them. To delete a variable, use the UUNNSSEETT command: UUNNSSEETT _v_a_r [_v_a_r...] For example, to delete all the variables declared above, use: UNSET a b mydir time date BBUUIILLTT--IINN FFUUNNCCTTIIOONNSS RReemmiinndd has a plethora of built-in functions. The syntax for a function call is the same as in C - the function name, followed a comma-separated list of arguments in parentheses. Function names are not case-sensitive. If a function takes no arguments, it must be followed by "()" in the function call. Otherwise, RReemmiinndd will interpret it as a variable name, and probably not work correctly. In the descriptions below, short forms are used to denote acceptable types for the arguments. The characters "i", "s", "d" and "t" denote IINNTT, SSTTRRIINNGG, DDAATTEE and TTIIMMEE argu- ments, respectively. If an argument can be one of several 11 November 1992 21 REMIND(1) REMIND(1) types, the characters are concatenated. For example, "di_arg" denotes an argument which can be a DDAATTEE or an IINNTT. "x_arg" denotes an argument which can be of any type. The type of the argument is followed by an under- score and an identifier naming the argument, for conve- nience. The built-in functions are: aabbss((ii__nnuumm)) Returns the absolute value of _n_u_m. aacccceessss((ss__ffiillee,, ssii__mmooddee)) Tests the access permissions for the file _f_i_l_e. _M_o_d_e can be a string, containing a mix of the char- acters "rwx" for read, write and execute permission testing. Alternatively, _m_o_d_e can be a number as described in the Unix aacccceessss(2) system call. The function returns 0 if the file can be accessed with the specified _m_o_d_e, and -1 otherwise. aasscc((ss__ssttrriinngg)) Returns an IINNTT which is the ASCII code of the first character in _s_t_r_i_n_g. As a special case, aasscc(("""")) returns 0. bbaasseeyyrr(()) Returns the "base year" which was compiled into RReemmiinndd (normally 1990.) All dates are stored internally as the number of days since 1 January of bbaasseeyyrr(()). cchhaarr((ii__ii11 [[,,ii__ii22......]])) This function can take any number of IINNTT arguments. It returns a SSTTRRIINNGG consisting of the characters specified by the arguments. Note that none of the arguments can be 0, unless there is only one argu- ment. As a special case, cchhaarr((00)) returns "". Note that because RReemmiinndd does not support escaping of characters in strings, the only way to get a double-quote in a string is to use cchhaarr((3344)). Yes, I know it's not portable - it assumes ASCII coding. cchhoooossee((ii__iinnddeexx,, xx__aarrgg11 [[,,xx__aarrgg22......]])) CChhoooossee must take at least two arguments, the first of which is an IINNTT. If _i_n_d_e_x is _n, then the _nth subsequent argument is returned. If _i_n_d_e_x is less than 1, then _a_r_g_1 is returned. If _i_n_d_e_x is greater than the number of subsequent arguments, then the last argument is returned. Examples: cchhoooossee((00,, ""ffoooo"",, 11::1133,, 11000000)) returns "foo" cchhoooossee((11,, ""ffoooo"",, 11::1133,, 11000000)) returns "foo" 11 November 1992 22 REMIND(1) REMIND(1) cchhoooossee((22,, ""ffoooo"",, 11::1133,, 11000000)) returns 1:13 cchhoooossee((33,, ""ffoooo"",, 11::1133,, 11000000)) returns 1000 cchhoooossee((44,, ""ffoooo"",, 11::1133,, 11000000)) returns 1000 Note that all arguments to cchhoooossee(()) are _a_l_w_a_y_s evaluated. ccooeerrccee((ss__ttyyppee,, xx__aarrgg)) This function converts _a_r_g to the specified _t_y_p_e, if such conversion is possible. _T_y_p_e must be one of "INT", "STRING", "DATE" or "TIME" (case- insensitive). The conversion rules are as follows: If _a_r_g is already of the _t_y_p_e specified, it is returned unchanged. If _t_y_p_e is "STRING", then _a_r_g is converted to a string consisting of its printed representation. If _t_y_p_e is "DATE", then an IINNTT _a_r_g is converted by interpreting it as the number of days since 1 Jan- uary bbaasseeyyrr(()). A SSTTRRIINNGG _a_r_g is converted by attempting to read it as if it were a printed date. A TTIIMMEE _a_r_g cannot be converted to a date. If _t_y_p_e is "TIME", then an IINNTT _a_r_g is converted by interpreting it as the number of minutes since mid- night. A SSTTRRIINNGG _a_r_g is converted by attempting to read it as if it were a printed time. A DDAATTEE _a_r_g cannot be converted to a time. If _t_y_p_e is "INT", then DDAATTEE and TTIIMMEE arguments are converted using the reverse of procedures described above. A SSTTRRIINNGG _a_r_g is converted by parsing it as an integer. ddaattee((ii__yy,, ii__mm,, ii__dd)) The ddaattee(()) function returns a DDAATTEE object with the year, month and day components specified by _y, _m and _d. ddaayy((dd__ddaattee)) This function takes a DDAATTEE as an argument, and returns an IINNTT which is the day-of-month component of _d_a_t_e. ddaayyssiimmoonn((ii__mm,, ii__yy)) Returns the number of days in month _m (1-12) of the year _y. ddeeffiinneedd((ss__vvaarr)) Returns 1 if the variable named by _v_a_r is defined, or 0 if it is not. Note that ddeeffiinneedd(()) takes a SSTTRRIINNGG argument; thus, to check if variable X is defined, use: 11 November 1992 23 REMIND(1) REMIND(1) defined("X") and not: defined(X) The second example will attempt to evaluate X, and will return an error if it is undefined or not of type SSTTRRIINNGG. ffiilleennaammee(()) Returns (as a SSTTRRIINNGG) the name of the current file being processed by RReemmiinndd. Inside included files, returns the name of the included file. ggeetteennvv((ss__eennvvvvaarr)) Similar to the ggeetteennvv(2) system call. Returns a string representing the value of the specified environment variable. Returns "" if the environ- ment variable is not defined. Note that the names of environment variables are generally case- sensitive; thus, getenv("HOME") is not the same as getenv("home"). hhoouurr((tt__ttiimmee)) Returns the hour component of _t_i_m_e. iiiiff((ssii__tteesstt,, xx__aarrggttrruuee,, xx__aarrggffaallssee)) If _t_e_s_t is not zero, and not the null string "", returns _a_r_g_t_r_u_e. Otherwise, returns _a_r_g_f_a_l_s_e. Note that all arguments are _a_l_w_a_y_s evaluated. iinnddeexx((ss__sseeaarrcchh,, ss__ttaarrggeett [[,,ii__ssttaarrtt)) Returns an IINNTT which is the location of _t_a_r_g_e_t in the string _s_e_a_r_c_h. The first character of a string is numbered 1. If _t_a_r_g_e_t does not exist in _s_e_a_r_c_h, then 0 is returned. The optional parameter _s_t_a_r_t specifies the position in _s_e_a_r_c_h at which to start looking for _t_a_r_g_e_t. iisslleeaapp((iidd__aarrgg)) Returns 1 if _a_r_g is a leap year, and 0 otherwise. _A_r_g can be either an IINNTT or a DDAATTEE object. If a DDAATTEE is supplied, then the year component is used in the test. iissoommiitttteedd((dd__ddaattee)) Returns 1 if _d_a_t_e is omitted, given the current global OOMMIITT context. Returns 0 otherwise. lloowweerr((ss__ssttrriinngg)) Returns a SSTTRRIINNGG with all upper-case characters in _s_t_r_i_n_g converted to lower-case. 11 November 1992 24 REMIND(1) REMIND(1) mmaaxx((xx__aarrgg11 [[,,xx__aarrgg22......)) Can take any number of arguments, and returns the maximum. The arguments can be of any type, but must all be of the same type. They are compared as with the > operator. mmiinn((xx__aarrgg11 [[,,xx__aarrgg22......)) Can take any number of arguments, and returns the minimum. The arguments can be of any type, but must all be of the same type. They are compared as with the < operator. mmiinnuuttee((tt__ttiimmee)) Returns the minute component of _t_i_m_e. mmoonn((ddii__aarrgg)) If _a_r_g is of DDAATTEE type, returns a string which names the month component of the date. If _a_r_g is an IINNTT from 1 to 12, returns a string which names the month. mmoonnnnuumm((dd__ddaattee)) Returns an IINNTT from 1 to 12, representing the month component of _d_a_t_e. nnooww(()) Returns the current system time, as a TTIIMMEE type. oorrdd((ii__nnuumm)) Returns a string which is the ordinal number _n_u_m. For example, oorrdd((22)) returns "2nd", and oorrdd((221133)) returns "213th". oossttyyppee(()) Returns "UNIX" on UNIX systems, "MSDOS" on MS-DOS systems, and "OS/2" on OS/2 systems. If you run RReemmiinndd in an MS-DOS box under OS/2, this function returns "MSDOS". pplluurraall((ii__nnuumm [[,,ss__ssttrr11 [[,,ss__ssttrr22]]]])) Can take from one to three arguments. If one argu- ment is supplied, returns "s" if _n_u_m is not 1, and "" if _n_u_m is 1. If two arguments are supplied, returns _s_t_r_1 + "s" if _n_u_m is not 1. Otherwise, returns _s_t_r_1. If three arguments are supplied, returns _s_t_r_1 if _n_u_m is 1, and _s_t_r_2 otherwise. rreeaallttooddaayy(()) Returns the date as provided by the operating sys- tem. This is in contrast to RReemmiinndd's concept of "today", which may be changed if it is running in calendar mode, or if a date has been supplied on the command line. 11 November 1992 25 REMIND(1) REMIND(1) ssggnn((ii__nnuumm)) Returns -1 if _n_u_m is negative, 1 if _n_u_m is posi- tive, and 0 if _n_u_m is zero. sshheellll((ss__ccmmdd)) Executes _c_m_d as a system command, and returns the first 511 characters of output resulting from _c_m_d. Any whitespace character in the output is converted to a space. Note that if RRUUNN OOFFFF has been exe- cuted, or the --rr command-line option has been used, sshheellll(()) will result in an error, and _c_m_d will not be executed. ssttrrlleenn((ss__ssttrr)) Returns the length of _s_t_r. ssuubbssttrr((ss__ssttrr,, ii__ssttaarrtt [[,,ii__eenndd]])) Returns a SSTTRRIINNGG consisting of all characters in _s_t_r from _s_t_a_r_t up to and including _e_n_d. Characters are numbered from 1. If _e_n_d is not supplied, then it defaults to the length of _s_t_r. ttiimmee((ii__hhrr,, ii__mmiinn)) Creates a TTIIMMEE with the hour and minute components specified by _h_r and _m_i_n. ttooddaayy(()) Returns RReemmiinndd's notion of "today." This may be the actual system date, or a date supplied on the command line, or the date of the calendar entry currently being computed. ttrriiggddaattee(()) Returns the calculated trigger date of the last RREEMM command. If used in the _b_o_d_y of a RREEMM command, returns that command's trigger date. ttrriiggggeerr((dd__ddaattee)) Returns a string suitable for use in a RREEMM command, allowing you to calculate trigger dates in advance. See the section "Expression pasting" for more information. ttrriiggttiimmee(()) Returns the time of the last RREEMM command with an AATT clause. ttrriiggvvaalliidd(()) Returns 1 if the value returned by ttrriiggddaattee(()) is valid for the most recent RREEMM command, or 0 other- wise. Sometimes RREEMM commands cannot calculate a trigger date. For example, the following RREEMM com- mand can never be triggered: 11 November 1992 26 REMIND(1) REMIND(1) REM Mon OMIT Mon SKIP MSG Impossible! ttyyppeeooff((xx__aarrgg)) Returns "STRING", "INT", "DATE" or "TIME", depend- ing on the type of _a_r_g. uuppppeerr((ss__ssttrriinngg)) Returns a SSTTRRIINNGG with all lower-case characters in _s_t_r_i_n_g converted to upper-case. vvaalluuee((ss__vvaarrnnaammee [[,,xx__ddeeffaauulltt]])) Returns the value of the specified variable. For example, value("X"+"Y") returns the value of vari- able XY, if it is defined. If XY is not defined, an error results. However, if you supply a second argument, it is returned if the _v_a_r_n_a_m_e is not defined. The expression value("XY", 0) will return 0 if XY is not defined, and the value of XY if it is defined. vveerrssiioonn(()) Returns a string specifying the version of RReemmiinndd. For version 03.00.01, returns "03.00.01". It is guaranteed that as new versions of RReemmiinndd are released, the value returned by vveerrssiioonn(()) will strictly increase, according to the rules for string ordering. wwkkddaayy((ddii__aarrgg)) If _a_r_g is a DDAATTEE, returns a string representing the day of the week of the date. If _a_r_g is an IINNTT from 0 to 6, returns the corresponding weekday ("Sunday" to "Saturday"). wwkkddaayynnuumm((dd__ddaattee)) Returns a number from 0 to 6 representing the day- of-week of the specified _d_a_t_e. (0 represents Sun- day, and 6 represents Saturday.) yyeeaarr((dd__ddaattee)) Returns a IINNTT which is the year component of _d_a_t_e. EEXXPPRREESSSSIIOONN PPAASSTTIINNGG An extremely powerful feature of RReemmiinndd is its macro capa- bility, or "expression pasting." In almost any situation where RReemmiinndd is not expecting an expression, you can "paste" an expression in. To do this, surround the expression with square brackets. For exam- ple: REM [trigger(mydate)] MSG foo 11 November 1992 27 REMIND(1) REMIND(1) This evaluates the expression "trigger(mydate)", where "mydate" is presumably some pre-computed variable, and then "pastes" the result into the command-line for the parser to process. A formal description of this is: When RReemmiinndd encounters a "pasted-in" expression, it evaluates the expression, and coerces the result to a SSTTRRIINNGG. It then substitutes the string for the pasted-in expression, and continues pars- ing. Note, however, that expressions are evaluated only once, not recursively. Thus, writing: ["[a+b]"] causes RReemmiinndd to read the token "[a+b]". It does not interpret this as a pasted-in expression. In fact, the only way to get a literal left-bracket into a reminder is to use ["["]. You can use expression pasting almost anywhere. However, there are a few exceptions: o If RReemmiinndd is expecting an expression, as in the SSEETT command, or the IIFF command, then no expression pasting takes place. The expression is simply evaluated as if the square brackets were not there. o You cannot use expression pasting for the first token on a line. For example, the following will not work: ["SET"] a 1 This restriction is because RReemmiinndd must be able to unambiguously determine the first token of a line for the flow-control commands (to be discussed later.) In fact, if RReemmiinndd cannot determine the first token on a line, it assumes that it is a RREEMM command. If expression-pasting is used, RReemmiinndd assumes it is a RREEMM command. Thus, the following three commands are equivalent: REM 12 Nov 1993 AT 13:05 MSG BOO! 12 Nov 1993 AT 13:05 MSG BOO! [12] ["Nov " + 1993] AT [12:05+60] MSG BOO! o You cannot use expression-pasting to determine the type (MMSSGG, CCAALL, etc.) of a RREEMM command. You can paste expressions before and after the MMSSGG, etc keywords, but cannot do something like this: REM ["12 Nov 1993 AT 13:05 " + "MSG" + " BOO!"] 11 November 1992 28 REMIND(1) REMIND(1) CCOOMMMMOONN PPIITTFFAALLLLSS IINN EEXXPPRREESSSSIIOONN PPAASSTTIINNGG Remember, when pasting in expressions, that extra spaces are not inserted. Thus, something like: REM[expr]MSG[expr] will probably fail. If you use an expression to calculate a _d_e_l_t_a or _b_a_c_k, ensure that the result is a positive number. Something like: REM +[mydelta] Nov 12 1993 MSG foo will fail if _m_y_d_e_l_t_a happens to be negative. FFLLOOWW CCOONNTTRROOLL CCOOMMMMAANNDDSS RReemmiinndd has commands which control the flow of a reminder script. Normally, reminder scripts are processed sequen- tially. However, IIFF and related commands allow you to process files conditionally, and skip sections which you don't want interpreted. TTHHEE IIFF CCOOMMMMAANNDD The IIFF command has the following form: IF expr t-command t-command... ELSE f-command f-command... ENDIF Note that the commands are shown indented for clarity. Also, the EELLSSEE portion can be omitted. IIFF commands can be nested up to a small limit, probably around 8 or 16 levels of nesting, depending on your system. If the _e_x_p_r evaluates to a non-zero IINNTT, or a non-null SSTTRRIINNGG, then the IIFF portion is considered true, and the _t_- _c_o_m_m_a_n_d_s are executed. If _e_x_p_r evaluates to zero or null, then the _f_-_c_o_m_m_a_n_d_s (if the EELLSSEE portion is present) are executed. If _e_x_p_r is not of type IINNTT or SSTTRRIINNGG, then it is an error. Examples: IF defined("want_hols") INCLUDE /usr/share/remind/holidays ENDIF 11 November 1992 29 REMIND(1) REMIND(1) IF today() > date(1992, 2, 10) set missed_ap "You missed it!" ELSE set missed_ap "Still have time..." ENDIF TTHHEE IIFFTTRRIIGG CCOOMMMMAANNDD The IIFFTTRRIIGG command is similar to an IIFF command, except that it computes a trigger (as in the RREEMM command), and evaluates to true if a corresponding RREEMM command would trigger. Examples: IFTRIG 1 Nov ; Executed on 1 Nov ELSE ; Executed except on 1 Nov ENDIF IFTRIG 1 -1 OMIT Sat Sun +4 ; Executed on last working day of month, ; and the 4 working days preceding it ELSE ; Executed except on above days ENDIF Note that the IIFFTTRRIIGG command computes a trigger date, which can be retrieved with the ttrriiggddaattee(()) function. You can use all of the normal trigger components, such as UUNNTTIILL, _d_e_l_t_a, etc in the IIFFTTRRIIGG command. UUSSEERR--DDEEFFIINNEEDD FFUUNNCCTTIIOONNSS In addition to the built-in functions, RReemmiinndd allows you to define your own functions. The FFSSEETT command does this for you: FFSSEETT _f_n_a_m_e(_a_r_g_s) _e_x_p_r _F_n_a_m_e is the name of the function, and follows the conven- tion for naming variables. _A_r_g_s is a comma-separated list of arguments, and _e_x_p_r is an expression. _A_r_g_s can be empty, in which case you define a function taking no parameters. Here are some examples: FSET double(x) 2*x FSET yeardiff(date1, date2) year(date1) - year(date2) FSET since(x) ord(year(trigdate())-x) The last function is useful in birthday reminders. For example: REM 1 Nov +12 MSG Dean's [since(1984)] birthday is %b. 11 November 1992 30 REMIND(1) REMIND(1) Dean was born in 1984. The above example, on 1 November 1992, would print: Dean's 8th birthday is today. Notes: o If you access a variable in _e_x_p_r which is not in the list of arguments, the "global" value (if any) is used. o Function and parameter names are significant only to 12 characters. o The vvaalluuee(()) function _a_l_w_a_y_s accesses the "global" value of a variable, even if it has the same name as an argument. For example: fset func(x) value("x") set x 1 set y func(5) The above sequence sets y to 1, which is the global value of x. o User-defined functions may call other functions, including other user-defined functions. However, recursive calls are not allowed. o User-defined functions are not syntax-checked when they are defined; parsing occurs only when they are called. o If a user-defined function has the same name as a built-in function, it is ignored and the built-in function is used. To prevent conflicts with future versions of RReemmiinndd (which may define more built-in functions), you may wish to name all user-defined functions beginning with an underscore. TTHHEE SSAATTIISSFFYY CCLLAAUUSSEE The form of RREEMM which uses SSAATTIISSFFYY is as follows: RREEMM _t_r_i_g_g_e_r SSAATTIISSFFYY _e_x_p_r The way this works is as follows: RReemmiinndd first calculates a trigger date, in the normal fashion. Next, it sets ttrriiggddaattee(()) to the calculated trigger date. It then evalu- ates _e_x_p_r. If the result is not the null string or zero, processing ends. Otherwise, RReemmiinndd computes the next trigger date, and re-tests _e_x_p_r. This iteration continues until _e_x_p_r evaluates to non-zero or non-null, or until the iteration limit specified with the --xx command-line option is reached. 11 November 1992 31 REMIND(1) REMIND(1) If _e_x_p_r is not satisfied, then ttrriiggvvaalliidd(()) is set to 0. Otherwise, ttrriiggvvaalliidd(()) is set to 1. In any event, no error message is issued. This is really useful only if _e_x_p_r involves a call to the ttrriiggddaattee(()) function; otherwise, _e_x_p_r will not change as RReemmiinndd iterates. An example of the usefulness of SSAATTIISSFFYY: Suppose you wish to be warned of every Friday the 13th. Your first attempt may be: # WRONG! REM Fri 13 +2 MSG Friday the 13th is %b. But this won't work. This reminder triggers on the first Friday on or after the 13th of each month. The way to do it is with a more complicated sequence: REM 13 SATISFY wkdaynum(trigdate()) == 5 IF trigvalid() REM [trigger(trigdate())] +2 MSG \ Friday the 13th is %b. ENDIF Let's see how this works. The SSAATTIISSFFYY clause iterates through all the 13ths of successive months, until a trig- ger date is found whose day-of-week is Friday (== 5). If a valid date was found, we use the calculated trigger date (converted into a trigger format with the ttrriiggggeerr(()) func- tion) to set up the next reminder. We could also have written: REM Fri SATISFY day(trigdate()) == 13 but this would result in more iterations, since "Fridays" occur more often than "13ths of the month." This technique of using one RREEMM command to calculate a trigger date to be used by another command is quite power- ful. For example, suppose you wanted to OMIT Labour day, which is the first Monday in September. You could use: # Note: SATISFY 1 is an idiom for "do nothing" REM Mon 1 Sept SATISFY 1 OMIT [trigger(trigdate())] CCAAVVEEAATT:: This _o_n_l_y omits the _n_e_x_t Labour Day, not all Labour Days in the future. This could cause strange results, as the OOMMIITT context can change depending on the current date. For example, if you use the following com- mand after the above commands: 11 November 1992 32 REMIND(1) REMIND(1) REM Mon AFTER msg hello the result will not be as you expect. Consider producing a calendar for September, 1992. Labour Day was on Monday, 7 September, 1992. However, when RReemmiinndd gets around to calculating the trigger for Tuesday, 8 September, 1992, the OOMMIITT command will now be ommitting Labour Day for 1993, and the "Mon AFTER" command will not be triggered. It is probably best to stay away from computing OOMMIITT trig- ger dates unless you keep these pitfalls in mind. DDEEBBUUGGGGIINNGG RREEMMIINNDDEERR SSCCRRIIPPTTSS Although the command-line --dd option is useful for debug- ging, it is often overkill. For example, if you turn on the --ddxx option for a reminder file with many complex expressions, you'll get a huge amount of output. The DDEEBBUUGG command allows you to control the debugging flags under program control. The format is: DDEEBBUUGG [+_f_l_a_g_s_o_n] [-_f_l_a_g_s_o_f_f] _F_l_a_g_s_o_n and _f_l_a_g_s_o_f_f consist of strings of the characters "extvl" which correspond to the debugging options dis- cussed in the command-line options section. If preceded with a "+", the corresponding group of debugging options is switched on. Otherwise, they are switched off. For example, you could use this sequence to debug a compli- cated expression: DEBUG +x set a very_complex_expression(many_args) DEBUG -x TTHHEE DDUUMMPPVVAARRSS CCOOMMMMAANNDD The command DDUUMMPPVVAARRSS displays the values of variables in memory. Its format is: DDUUMMPPVVAARRSS [_v_a_r...] If you supply a space-separated list of variable names, the corresponding variables are displayed. If you do not supply a list of variables, then all variables in memory are displayed. TTHHEE EERRRRMMSSGG CCOOMMMMAANNDD The EERRRRMMSSGG command has the following format: EERRRRMMSSGG _b_o_d_y The _b_o_d_y is passed through the substitution filter (with 11 November 1992 33 REMIND(1) REMIND(1) an implicit trigger date of ttooddaayy(())) and printed to the error output stream. Example: IF !defined("critical_var") ERRMSG You must supply a value for "critical_var" EXIT ENDIF TTHHEE EEXXIITT CCOOMMMMAANNDD The above example also shows the use of the EEXXIITT command. This causes an unconditional exit from script processing. Any queued timed reminders are discarded. If you are in calendar mode (described next), then the calendar process- ing is aborted. CCAALLEENNDDAARR MMOODDEE If you supply the --cc, --ss or --pp command-line option, then RReemmiinndd runs in "calendar mode." In this mode, RReemmiinndd interprets the script repeatedly, performing one iteration through the whole file for each day in the calendar. Reminders which trigger are saved in internal buffers, and then inserted into the calendar in the appropriate places. The --pp option is used in conjunction with the rreemm22ppss pro- gram to produce a calendar in PostScript format. For example, the following command will send PostScript code to standard output: remind -p .reminders | rem2ps You can print a PostScript calendar by piping this to the llpprr command. If you have a reminder script called ".reminders", and you execute this command: remind -c .reminders jan 1993 then RReemmiinndd executes the script 31 times, once for each day in January. Each time it executes the script, it increments the value of ttooddaayy(()). Any reminders whose trigger date matches ttooddaayy(()) are entered into the calen- dar. MMSSGG and CCAALL-type reminders, by default, have their entire body inserted into the calendar. RRUUNN-type reminders are not normally inserted into the calendar. However, if you enclose a portion of the body in the %"...%" sequence, only that portion is inserted. For example, consider the following: REM 6 Jan MSG %"David's birthday%" is %b 11 November 1992 34 REMIND(1) REMIND(1) In the normal mode, RReemmiinndd would print "David's birthday is today" on 6 January. However, in the calendar mode, only the text "David's birthday" is inserted into the box for 6 January. If you explicitly use the %"...%" sequence in a RRUUNN-type reminder, then the text between the delimiters is inserted into the calendar. If you use the sequence %"%" in a MMSSGG or CCAALL-type reminder, then no calendar entry is produced for that reminder. PPRREESSEERRVVIINNGG VVAARRIIAABBLLEESS Because RReemmiinndd iterates through the script for each day in the calendar, slow operations may severely reduce the speed of producing a calendar. For example, suppose you set the variables "me" and "host- name" as follows: SET me shell("whoami") SET hostname shell("hostname") Normally, RReemmiinndd clears all variables between iterations in calendar mode. However, if certain variables are slow to compute, and will not change between iterations, you can "preserve" their values with the PPRREESSEERRVVEE command. Also, since function definitions are preserved between calendar iterations, there is no need to redefine them on each iteration. Thus, you could use the following sequence: IF ! defined("initialized") set initialized 1 set me shell("whoami") set hostname shell("hostname") fset func complex_expr() preserve initialized me hostname ENDIF The operation is as follows: On the first iteration through the script, "initialized" is not defined. Thus, the commands between IIFF and EENNDDIIFF are executed. The PPRREE-- SSEERRVVEE command ensures that the values of initialized, me and hostname are preserved for subsequent iterations. On the next iteration, the commands are skipped, since ini- tialized has remained defined. Thus, time-consuming oper- ations which do not depend on the value of ttooddaayy(()) are done only once. Note that for efficiency, RReemmiinndd caches the reminder script (and any IINNCCLLUUDDEEd files) in memory when producing a calendar. 11 November 1992 35 REMIND(1) REMIND(1) Timed reminders are sorted and placed into the calendar in time order. These are followed by non-timed reminders. RReemmiinndd automatically places the time of timed reminders in the calendar according to the --bb command-line option. DDAAEEMMOONN MMOODDEE If you use the --zz command-line option, RReemmiinndd runs in the "daemon" mode. In this mode, no "normal" reminders are issued. Instead, only timed reminders are collected and queued, and are then issued whenever they reach their trigger time. In addition, RReemmiinndd wakes up every few minutes to check the modification date on the reminder script (the filename supplied on the command line.) If RReemmiinndd detects that the script has changed, it re-executes itself in daemon mode, and interprets the changed script. In daemon mode, RReemmiinndd also re-reads the remind script when it detects that the system date has changed. In daemon mode, RReemmiinndd acts as if the --ff option had been used, so to run in the daemon mode in the background, use: remind -z .reminders & If you use sshh or bbaasshh, you may have to use the "nohup" command to ensure that the daemon is not killed whn you log out. MMIISSCCEELLLLAANNEEOOUUSS CCOOMMMMAANNDD AABBBBRREEVVIIAATTIIOONNSS The following commands can be abbreviated: o RREEMM can be omitted - it is implied if no other valid command is present. o CCLLEEAARR--OOMMIITT--CCOONNTTEEXXTT --> CCLLEEAARR o PPUUSSHH--OOMMIITT--CCOONNTTEEXXTT --> PPUUSSHH o PPOOPP--OOMMIITT--CCOONNTTEEXXTT --> PPOOPP o DDUUMMPPVVAARRSS --> DDUUMMPP o BBAANNNNEERR --> BBAANN o IINNCCLLUUDDEE --> IINNCC NNIIFFTTYY EEXXAAMMPPLLEESS 11 November 1992 36 REMIND(1) REMIND(1) This section is a sampling of what you can do with RReemmiinndd. REM 5 Feb 1991 AT 14:00 +45 *30 \ RUN mail -s "Meeting at %2" $LOGNAME </dev/null & On 5 February, 1991, this reminder will mail you reminders of a 2:00pm meeting at 1:15, 1:45 and 2:00. The subject of the mail message will be "Meeting at 2:00pm" and the body of the message will be blank. REM AT 17:00 RUN echo "5:00pm - GO HOME!" | xless -g +0+0 & This reminder will pop up an xless window at 5:00pm every day. The xless window will contain the line "5:00pm - GO HOME!" REM AT 23:59 RUN (sleep 120; remind -a [filename()]) & This reminder will run at one minute to midnight. It will cause a new remind process to start at one minute past midnight. This allows you to have a continuous reminder service so you can work through the night and still get timed reminders for early in the morning. Note that this trick is no longer necessary, providing you run RReemmiinndd in daemon mode. remind -c12 /dev/null Jan 1993 This invocation of rreemmiinndd will cause it to print a calen- dar for 1993, with all entries left blank. REM CAL [trigdate()-date(year(trigdate()), 1, 1)+1] This example puts an entry in each box of a calendar show- ing the number (1-365 or 366) of the day of the year. REM Tue 2 Nov SATISFY (year(trigdate())%4) == 0 IF trigvalid() REM [trigger(trigdate())] ++5 MSG \ U.S. Presidential Election!! ENDIF This example warns you 5 days ahead of each American pres- idential election. The first RREEMM command calculates the first Tuesday after the first Monday in November. (This is equivalent to the first Tuesday on or after 2 Novem- ber.) The SSAATTIISSFFYY clause ensures that the trigger date is issued only in election years, which are multiples of 4. The second RREEMM command actually issues the reminder. DDEETTAAIILLSS AABBOOUUTT TTRRIIGGVVAALLIIDD(()) The ttrriiggvvaalliidd(()) function returns 1 if RReemmiinndd could find a trigger date for the previous RREEMM or IIFFTTRRIIGG command. More 11 November 1992 37 REMIND(1) REMIND(1) specifically, it returns 1 if RReemmiinndd finds a date _n_o_t _i_n _t_h_e _p_a_s_t which satisfies the trigger. In addition, there is one special case in which ttrriiggvvaalliidd(()) returns 1 and ttrriiggddaattee(()) returns a meaningful result: If the RREEMM or IIFFTTRRIIGG command did not contain an UUNNTTIILL clause, and contained all of the _d_a_y, _m_o_n_t_h and _y_e_a_r com- ponents, then RReemmiinndd will correctly compute a trigger date, even if it happens to be in the past. Note that this behaviour is not true for versions of RReemmiinndd prior to 03.00.01. AAUUTTHHOORR David F. Skoll BBUUGGSS Date calculation is a bit "brute force." The MS-DOS and 16-bit OS/2 versions of RReemmiinndd do not sup- port queuing or timed activation of reminders. RReemmiinndd has some built-in limits on total line length, sub- stitution buffer length, number of global OOMMIITTs, etc. SSEEEE AALLSSOO rem, elm, kall, rem2ps 11 November 1992 38